home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / tools / gcc / gcc270_doc.lha / gnu / man / cat1 / gprof.0 < prev    next >
Encoding:
Text File  |  1995-08-24  |  8.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GPROF(1)                                                 GPROF(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        gprof - display call graph profile data
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ggpprrooff  [[ --aabbccsszz ]] [[ --ee||--EE _n_a_m_e ]] [[ --ff||--FF _n_a_m_e ]] [[ --kk _f_r_o_m_-
  12.        _n_a_m_e _t_o_n_a_m_e ]] [[ _o_b_j_f_i_l_e [[ _g_m_o_n_._o_u_t ]] ]]
  13.  
  14. DDEESSCCRRIIPPTTIIOONN
  15.        ggpprrooff produces an execution profile of C, Pascal, or  For-
  16.        tran77  programs.  The effect of called routines is incor-
  17.        porated in the profile of each caller.  The  profile  data
  18.        is  taken  from  the  call  graph profile file (`gmon.out'
  19.        default) which is created by programs  that  are  compiled
  20.        with  the --ppgg option of cccc(11),, ppcc(11),, and ff7777(11)..  The --ppgg
  21.        option also links in versions of the library routines that
  22.        are  compiled for profiling.  GGpprrooff reads the given object
  23.        file (the default is `a.out') and establishes the relation
  24.        between  its  symbol table and the call graph profile from
  25.        `gmon.out'.  If more than one profile file  is  specified,
  26.        the  ggpprrooff output shows the sum of the profile information
  27.        in the given profile files.
  28.  
  29.        GGpprrooff calculates the amount of time spent in each routine.
  30.        Next,  these  times  are propagated along the edges of the
  31.        call graph.  Cycles are discovered, and calls into a cycle
  32.        are  made to share the time of the cycle.  The first list-
  33.        ing shows the functions sorted according to the time  they
  34.        represent  including  the time of their call graph descen-
  35.        dents.  Below each function entry is  shown  its  (direct)
  36.        call graph children, and how their times are propagated to
  37.        this function.  A similar display above the function shows
  38.        how  this  function's time and the time of its descendents
  39.        is propagated to its (direct) call graph parents.
  40.  
  41.        Cycles are also shown, with an entry for the  cycle  as  a
  42.        whole  and a listing of the members of the cycle and their
  43.        contributions to the time and call counts of the cycle.
  44.  
  45.        Second, a flat profile is given, similar to that  provided
  46.        by pprrooff(11)..  This listing gives the total execution times,
  47.        the call counts, the time in milleseconds the  call  spent
  48.        in  the  routine  itself, and the time in milleseconds the
  49.        call spent in the routine  itself  including  its  descen-
  50.        dents.
  51.  
  52.        Finally, an index of the function names is provided.
  53.  
  54. OOPPTTIIOONNSS
  55.        The following options are available:
  56.  
  57.        --aa     suppresses  the  printing  of  statically  declared
  58.               functions.  If this option is given,  all  relevant
  59.               information  about  the static function (e.g., time
  60.               samples, calls to other functions, calls from other
  61.  
  62.  
  63.  
  64.                          January 29, 1993                       1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GPROF(1)                                                 GPROF(1)
  71.  
  72.  
  73.               functions)  belongs  to  the  function  loaded just
  74.               before the static function in the `objfile' file.
  75.  
  76.        --bb     suppresses the printing of a  description  of  each
  77.               field in the profile.
  78.  
  79.        --cc     the  static call graph of the program is discovered
  80.               by a heuristic that examines the text space of  the
  81.               object  file.   Static-only parents or children are
  82.               shown with call counts of 0.
  83.  
  84.        --ee _n_a_m_e
  85.               suppresses the printing of the graph profile  entry
  86.               for  routine  _n_a_m_e  and all its descendants (unless
  87.               they have other ancestors that aren't  suppressed).
  88.               More  than  one  --ee  option may be given.  Only one
  89.               _n_a_m_e may be given with each --ee option.
  90.  
  91.        --EE _n_a_m_e
  92.               suppresses the printing of the graph profile  entry
  93.               for  routine  _n_a_m_e  (and  its  descendants) as --ee ,,
  94.               above, and also excludes the  time  spent  in  _n_a_m_e
  95.               (and its descendants) from the total and percentage
  96.               time computations.   (For  example,  --EE  _m_c_o_u_n_t  --EE
  97.               _m_c_l_e_a_n_u_p is the default.)
  98.  
  99.        --ff _n_a_m_e
  100.               prints  the  graph profile entry of only the speci-
  101.               fied routine _n_a_m_e and its descendants.   More  than
  102.               one  --ff  option may be given.  Only one _n_a_m_e may be
  103.               given with each --ff option.
  104.  
  105.        --FF _n_a_m_e
  106.               prints the graph profile entry of only the  routine
  107.               _n_a_m_e  and  its descendants (as --ff ,, above) and also
  108.               uses only the times  of  the  printed  routines  in
  109.               total  time and percentage computations.  More than
  110.               one --FF option may be given.  Only one _n_a_m_e  may  be
  111.               given with each --FF option.  The --FF option overrides
  112.               the --EE option.
  113.  
  114.        --kk _f_r_o_m_n_a_m_e _t_o_n_a_m_e
  115.               will delete any arcs from routine _f_r_o_m_n_a_m_e to  rou-
  116.               tine  _t_o_n_a_m_e.   This can be used to break undesired
  117.               cycles.  More than one  --kk  option  may  be  given.
  118.               Only  one  pair  of routine names may be given with
  119.               each --kk option.
  120.  
  121.        --ss     a profile file `gmon.sum' is produced  that  repre-
  122.               sents the sum of the profile information in all the
  123.               specified profile files.  This summary profile file
  124.               may be given to later executions of gprof (probably
  125.               also with a --ss) to accumulate profile  data  across
  126.               several runs of an `objfile' file.
  127.  
  128.  
  129.  
  130.                          January 29, 1993                       2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GPROF(1)                                                 GPROF(1)
  137.  
  138.  
  139.        --vv     prints  the  version  number  for  gprof,  and then
  140.               exits.
  141.  
  142.        --zz     displays routines that have zero usage (as shown by
  143.               call  counts and accumulated time).  This is useful
  144.               with the --cc option for discovering  which  routines
  145.               were never called.
  146.  
  147.  
  148. FFIILLEESS
  149.        a.out    the namelist and text space.
  150.        gmon.out dynamic call graph and profile.
  151.        gmon.sum summarized dynamic call graph and profile.
  152.  
  153. SSEEEE AALLSSOO
  154.        mmoonniittoorr(33),, pprrooffiill(22),, cccc(11),, pprrooff(11)
  155.  
  156.        ``An Execution Profiler for Modular Programs'', by S. Gra-
  157.        ham, P. Kessler, M.  McKusick;  _S_o_f_t_w_a_r_e  _-  _P_r_a_c_t_i_c_e  _a_n_d
  158.        _E_x_p_e_r_i_e_n_c_e_, Vol. 13, pp. 671-685, 1983.
  159.  
  160.        ``gprof:  A Call Graph Execution Profiler'', by S. Graham,
  161.        P. Kessler, M. McKusick; _P_r_o_c_e_e_d_i_n_g_s _o_f  _t_h_e  _S_I_G_P_L_A_N  _'_8_2
  162.        _S_y_m_p_o_s_i_u_m  _o_n _C_o_m_p_i_l_e_r _C_o_n_s_t_r_u_c_t_i_o_n_, SIGPLAN Notices, Vol.
  163.        17, No  6, pp. 120-126, June 1982.
  164.  
  165. HHIISSTTOORRYY
  166.        GGpprrooff appeared in 4.2 BSD.
  167.  
  168. BBUUGGSS
  169.        The granularity of the sampling is shown, but remains sta-
  170.        tistical at best.  We assume that the time for each execu-
  171.        tion of a function can be expressed by the total time  for
  172.        the  function  divided by the number of times the function
  173.        is called.  Thus the time propagated along the call  graph
  174.        arcs to the function's parents is directly proportional to
  175.        the number of times that arc is traversed.
  176.  
  177.        Parents that are not themselves  profiled  will  have  the
  178.        time  of  their  profiled children propagated to them, but
  179.        they will appear to be spontaneously invoked in  the  call
  180.        graph  listing,  and  will  not have their time propagated
  181.        further.  Similarly, signal  catchers,  even  though  pro-
  182.        filed,  will  appear  to be spontaneous (although for more
  183.        obscure reasons).  Any profiled children of signal  catch-
  184.        ers  should  have  their times propagated properly, unless
  185.        the signal catcher was invoked during the execution of the
  186.        profiling routine, in which case all is lost.
  187.  
  188.        The  profiled program must call eexxiitt(22) or return normally
  189.        for  the  profiling  information  to  be  saved   in   the
  190.        `gmon.out' file.
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                          January 29, 1993                       3
  197.  
  198.  
  199.